home *** CD-ROM | disk | FTP | other *** search
/ MACD 5 / MACD 5.bin / workbench / tools / czesc_3 / psm / readme.txt < prev    next >
Text File  |  1993-07-28  |  9KB  |  202 lines
  1.  
  2. PSM - Public Screen Manager v1.0
  3. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  4. Copyright (C)1993 by Dianne Hackborn.
  5.  
  6. =========================================================================
  7. This program is shareware.  If you like it and find it useful, please
  8. consider sending a donation of $5 or whatever you think it is worth. 
  9. My address is at the end of this file.
  10.  
  11. Taking a clue from Microsoft and their MSDOG 6.0, if you become a
  12. register developer of my gadoutline.library, you will also become
  13. registered for this program at NO EXTRA CHARGE!  Wow. :)
  14.  
  15. This program is freely distributable as long as all of its files are
  16. included, with no modifications to them.  It is provided as-is, and has
  17. warranties of any kind.
  18. =========================================================================
  19.  
  20. INTRODUCTION
  21.  
  22. PSM is Yet Another Public Screen Program.  It was primarily written as
  23. a demonstration of my gadoutline.library, and is thus currently very
  24. GUIcentric - it does no command line parsing for CLI users or even look
  25. at its Workbench tooltypes.  On the other hand, it does have a very
  26. sophisticated multi-window user interface and allow almost complete
  27. control over the creation of screens.
  28.  
  29. This program requires gadoutline.library to run, which is included in
  30. the archive.  You may either place the library in your LIBS: directory
  31. or in the same directory as PSM; if it can't find it in LIBS: it will
  32. attempt to load it from its program directory.  The included program
  33. "AboutGadOutline" displays information about the gadoutline.library
  34. file currently installed.  Complete documentation and programming
  35. information for gadoutline.library is available in a separate
  36. distribution.
  37.  
  38. GETTING STARTED
  39.  
  40. There are three different windows used by PSM: The MAIN WINDOW, the
  41. EXAMINE WINDOW and the NEWSCREEN WINDOW.  PSM allows multiple windows
  42. - limited only by memory - to be open and active at the same time.  You
  43. could, for example, open a newscreen window and, while filling it in,
  44. get information from another screen by opening an examine window or even
  45. another newscreen window; the first window will not be disturbed in any
  46. way.  The only exception to this independence is the main window, as
  47. discussed below.
  48.  
  49. THE MAIN WINDOW
  50.  
  51. PSM's main window is the first thing you should see after running the
  52. program, and is the main control panel for everything else.  You can
  53. only have one main window open for a single invocation of the program,
  54. and closing this window will cause all other windows currently opened
  55. by the application to be closed and the program to exit.  In addition,
  56. all other windows are opened from the main window, and all open windows
  57. [with the exception noted later] follow the main window to whatever
  58. screen it is on.
  59.  
  60. There are two primary components of the window - the top 3/4 of the
  61. window allows the viewing and selection of all available public
  62. screens, while the bottom 2 lines contain other miscellaneous
  63. functions.  At the very top of the window is a list of public screens;
  64. each entry corresponds to one public screen, and contains three
  65. distinct fields:
  66.  
  67.  F## Name...
  68.  | | |
  69.  | | +------------ Public screen's name
  70.  | +----------Number of locks on the screen
  71.  +-----Screen state.  P=Private, *=A PSM Screen, blank is 'normal.'
  72.  
  73. Directly below this list is a box labeled "Owner", which identifies
  74. any task which will be notified when the last window on the screen
  75. closes; if there is no task, it will display "None."
  76.  
  77. The screen list is used to selecte which screen an operation is to be
  78. performed on.  The next three lines contain buttons for the following
  79. operations:
  80.  
  81. Close - Attempts to close the selected screen.  This gadget will be
  82.         disabled if there are any locks on the screen.
  83. Jump to - Move to the selected screen; the main window and all other
  84.           opened windows will jump to that screen.
  85. Examine - Open examine window for selected screen.
  86. Dup Scrn - Open NewScreen window, with defaults from selected screen.
  87. Mod Scrn - Open NewScreen window in special modify mode on the selected
  88.            screen.  Disabled if the screen has any locks.
  89. Default - Select screen as the default public screen.  To the right it
  90.           displays the current default screen.
  91.  
  92. Finally, the last two lines contain four miscellaneous control gadgets:
  93.  
  94. Shanghai - Select shanghai mode; when on, all windows trying to open on
  95.            the workbench screen will be forced on to the default public
  96.            screen.
  97. AutoPop - Select auto pop mode; when on, a public screen will
  98.           automatically move to the front when a window opens on it.
  99. New Scrn - Bring up NewScreen window based on default public screen.
  100. Quit - Exit program.  Same as selecting the window's close gadget.
  101.  
  102. THE EXAMINE WINDOW
  103.  
  104. This window is used to look at basic information about a screen; it is
  105. opened by selecting "Examine" from the main window.  Note that the
  106. information in the window is only a snapshot created at the time the
  107. window is opened; any later changes to the screen will not be reflected
  108. in the window.
  109.  
  110. THE NEWSCREEN WINDOW
  111.  
  112. This window is used to open a new public screen.  At the top are two
  113. string gadgets, used to specify the public name the screen will be
  114. refered to by, and the title to place in the screen's title bar.  Note
  115. that the public screen name must be unique to this screen and is case
  116. sensitive.
  117.  
  118. Below these are two large boxes; the left is a standard list of display
  119. modes which the screen can be opened in, and the box to the right shows
  120. general information about the currently selected display mode.
  121.  
  122. Below the display mode is a group of gadgets used to specify the
  123. screen's overscan information.  At the top is a cycle gadget of
  124. standard overscan regions.  If you select "Custom" for the region, the
  125. four gadgets below it will be activated, allowing you to specify the
  126. top-left and bottom-right corners of the display region.
  127.  
  128. To the right of the overscan gadgets are the screen size gadgets.  You
  129. may either choose to use the default dimension or a custom dimension
  130. for both the screen's width and height.  Using a custom dimension, you
  131. may create a screen either larger or smaller than the selected overscan
  132. region.  Below these gadgets is a single checkbox used to turn
  133. autoscroll on and off.  When opening a screen larger than the overscan
  134. size, turning this on will allow the screen to automatically scroll
  135. when you move the pointer to its edge.
  136.  
  137. At the bottom is a group of gadgets used to select the screen's font,
  138. and the "Open" button which will actually create the screen.
  139.  
  140. Finally, at the far right is two groups of gadgets used to control the
  141. screen's depth, palette and drawing pens.
  142.  
  143. THE MODIFY WINDOW
  144.  
  145. There is a special mode of the NewScreen window called "Modify."  This
  146. mode is enabled whenever the Modify button is selected from the main
  147. window, or after a screen is opened with NewScreen and the window pops
  148. up on the newly created screen.  This window has some special
  149. characteristics:
  150.  
  151.     - It is attached to the screen it is on, and will not move from it
  152.       when you select "Jump to" from the main window.
  153.     - It changes the screen's palette as the window's palette gadgets
  154.       are played with by the user.
  155.     - The "Open" gadget is replaced with a "Modify" gadget, which
  156.       closes the screen and then reopens it with any changes that have
  157.       been made through the window.  This makes it very easy to try out
  158.       different overscan, screen mode, font, size, depth and draw pen
  159.       settings until you find something that you like.
  160.  
  161. Be aware that this window's attachment to its screen is _only_ through
  162. its "Public Name" gadget at the top; when changing the palette or
  163. selecting the modify gadget, this is the screen which is taken to be
  164. the one being modified.
  165.  
  166. SCREEN TRACKING
  167.  
  168. When opening a screen, a program needs to provide Intuition with some
  169. information that remains valid throughout the screen's lifetime.
  170. Because of this, PSM employs a method of tracking screens it has
  171. opened, which allows it to free these resources when closing the
  172. screen.  Screens that are currently being tracked by it are marked with
  173. the '*' flag in the main window; if one of these screens is closed by
  174. anything besides PSM, you will loose the 100-200 bytes of memory being
  175. tracked until you reboot your computer.
  176.  
  177. The method that PSM uses to track these screens allows it to track them
  178. between separate invocations of the program or even among multiple
  179. invocations of the program running at the same time.
  180.  
  181. THE SOURCE CODE
  182.  
  183. This archive includes all source code needed to create the program.  If
  184. you own SAS/C v6.0 or later, you should be able to compile it by simply
  185. double clicking on the build icon in the source directory.  Note that
  186. you will need the gadoutline.library include files in the compiler's
  187. search path in order to get it to compile.
  188.  
  189. HOW TO REACH ME
  190.  
  191. EMail -     BIX: dhack@bix.com
  192.             SCHOOL: hackbod@xanth.cs.orst.edu
  193.  
  194. SnailMail - Dianne Hackborn
  195.             2895 Los Altos Drive
  196.             Meridian, ID 83642
  197.             
  198. FINALLY
  199.  
  200.     Have fun, and I hope you find the program useful.  All comments,
  201.     suggestions and bug reports are more than welcome.
  202.